home *** CD-ROM | disk | FTP | other *** search
/ The CICA Windows Explosion! / The CICA Windows Explosion! - Disc 2.iso / programr / dpmigcc5.zip / RSX / DOC / DPMILB11.TXT < prev    next >
Text File  |  1994-12-12  |  16KB  |  435 lines
  1. -------------------------------------------------
  2. Copyright    Rainer Schnitker    '91 '92
  3. -------------------------------------------------
  4.  
  5.  
  6. THE DPMI INTERFACE :
  7.  
  8. This is a short documentation for the interface functions.
  9. For details, read the DPMI-specification 0.9 .
  10. DOS Extenders and DPMI is described in some special books like:
  11. Ray Duncan "Extended Dos".
  12.  
  13.  
  14. Most DPMI-functions return 0 if successful, -1 on error
  15.         (later error code of DPMI 1.0).
  16.  
  17.  
  18. ****** LDT Descriptor management services  DPMI 0.9 ******
  19.  
  20. Constants in dpmi.h for LDT management:
  21.     - set access rights for descriptors
  22.         ACCESS_BIT, READ_BIT, WRITE_BIT, CONFIRMING_BIT, EXPAND_BIT,
  23.                 CODE_BIT, SEGMENT_BIT, PRESENT_BIT
  24.         AVL_BIT, DEFAULT_BIT, GRANULAR_BIT
  25.     - mask out special fields in descriptor
  26.         DPL_MASK, TYPE_MASK, LIMIT_HI_MASK
  27.     - normal access type for dpl3 programs
  28.         APP_CODE_SEL, APP_DATA_SEL
  29.     - types of gates
  30.         TYPE_CODE, TYPE_CONFIRM_CODE, TYPE_DATA, TYPE_EXPAND_DATA,
  31.                 TYPE_286TSS, TYPE_LDT, TYPE_BUSY286TSS, TYPE_286CALLGATE
  32.                 TYPE_TASKGATE, TYPE_286INTGATE, TYPE_286TRAPGATE,
  33.                 TYPE_386TSS, TYPE_BUSY386TSS, TYPE_386CALLGATE
  34.                 TYPE_386INTGATE, TYPE_386TRAPGATE
  35.  
  36. int AllocLDT(WORD n,WORD *firstselector);
  37.         - this allocates n descriptors from the Local Descriptor Table
  38.         - add the value returned from function SelInc() to get the next selector
  39.     - the descriptors will be set to present data type, base=0, limit=0
  40.  
  41. int FreeLDT(WORD selector);
  42.         - this function is used to free descriptors that were allocated
  43.           by the function AllocLDT()
  44.  
  45. int SegtoSel(WORD realsegment,WORD *selector);
  46.         - this converts real mode segments into descriptors
  47.         - selector has limit 64 KB
  48.  
  49. WORD SelInc(void);
  50.         - return the increment value to get the next selector (typical 8).
  51.         - function can't fail
  52.  
  53. int LockSel(WORD selector);
  54.         - undocumented function
  55.         - this locks the address area of the selector
  56.  
  57. int UnlockSel(WORD selector);
  58.         - undocumented function
  59.         - this function is used to unlock the memory area
  60.  
  61. int GetBaseAddress(WORD selector,DWORD *address);
  62.         - gives the 32bit-linear address of the selector
  63.  
  64. int SetBaseAddress(WORD selector ,DWORD 32bitaddress);
  65.         - set the base address of the specified selector
  66.  
  67. int SetLimit(WORD sel,DWORD limit);
  68.     - set the limit for the selector (note: limit = blocksize - 1)
  69.     - if limit > 1 MB, low 12 bits must be set
  70.       (then the granular bit will be set)
  71.         - to get the limit use the function lsl32() or lsl16()
  72.  
  73. int SetAccess(WORD,BYTE accessbyte,BYTE 386extendedbyte);
  74.         - set access rights for the selector
  75.         - SEGMENT-bit must be set. You can't create a system descriptor.
  76.         - to get the access right use the function lar32() or lar16()
  77.  
  78. int CreatAlias(WORD codeselector,WORD *alias_selector);
  79.         - this creates a data descriptor with the same address and limit as
  80.           the code descriptor
  81.  
  82. int GetDescriptor(WORD selector,NPDESCRIPTOR buffer);
  83.         - this copies the 8 bytes descriptor table into the buffer
  84.  
  85. int SetDescriptor(WORD selector,NPDESCRIPTOR buffer);
  86.         - this function is used to set a descriptor
  87.  
  88. int AllocSpecialLDT(WORD selector);
  89.         - this allocates a specific LDT descriptor
  90.  
  91.  
  92. ****** DOS Memory Services DPMI 0.9 ******
  93.  
  94. int AllocDosMem(WORD paragraphs,WORD *segment,WORD *selector);
  95.         - multiple contiguous selectors are allocated for blocks of more
  96.           than 64K
  97.         - if the caller is a 16-bit program never modify or
  98.           deallocate returned descriptors
  99.         - return 0 if successful, else DOS errors:
  100.           07h memory control blocks damaged
  101.           08h insufficient memory available
  102.  
  103. int FreeDosMem(WORD selector);
  104.         - all descriptors allocated for the block are automatically freed
  105.  
  106. int ResizeDosMem(WORD newparagraphs,WORD oldselector,WORD *newselector);
  107.         - increasing the size of a block past a 64K boundary will fail if the
  108.       next descriptor in the LDT is already in use
  109.         - shrinking a block past a 64K boundary will cause some selectors to
  110.           be freed
  111.  
  112.  
  113. ****** Interrupt Services DPMI 0.9 ******
  114.  
  115. int GetRealModeVector(BYTE intnumber,WORD segment*,WORD *offset);
  116.         - get real mode interrupt vector
  117.  
  118. int SetRealModeVector(BYTE intnumber,WORD segment,WORD offset);
  119.         - set real mode interrupt vector
  120.         - hardware interrupt handler memory must be locked
  121.  
  122. int GetExceptionVektor(BYTE intnumber,WORD *selector,WORD *offset);
  123.         - give the current protected mode exception handler
  124.  
  125. int SetExceptionVektor(BYTE intnumber,WORD selector,WORD offset);
  126.         - set new protected mode exception handler
  127.         - read DPMI-specification 0.9 for some details
  128.         - use higher C-level functions, described later SetExcep13 etc.
  129.  
  130. int GetProtModeVector(BYTE,WORD *selector,WORD *offset);
  131.         - get the current protected mode interrupt handler
  132.  
  133. int SetProtModeVektor(BYTE,WORD selector,WORD offset);
  134.         - set new protected mode interrupt handler
  135.  
  136.  
  137. ****** Translation services DPMI 0.9 ******
  138.  
  139. int SimulateRMint(BYTE intnr,BYTE flags,WORD stackwords,NPTRANSLATION call,...)
  140.         - CS:IP in the real mode call structure is ignored for this call,
  141.       instead, the indicated interrupt vector is used for the address
  142.         - the flags in the call structure are pushed on the real mode stack to
  143.       form an interrupt stack frame, and the trace and interrupt flags are
  144.       clear on entry to the handler
  145.         - DPMI will provide a small (30 words) real mode stack if SS:SP is zero
  146.           the real mode handler must return with the stack in the same state as
  147.       it was on being called
  148.  
  149. int CallRMprocFar(BYTE flags,WORD stackwords,NPTRANSLATION call,...)
  150.         - the real mode procedure must exit with a FAR return
  151.         - DPMI will provide a small (30 words) real mode stack if SS:SP is zero
  152.         - the real mode handler must return with the stack in the same state as
  153.       it was on being called
  154.  
  155. int CallRMprocIret(BYTE flags,WORD stackwords,NPTRANSLATION call,...)
  156.         - the real mode procedure must exit with an IRET
  157.  
  158. int AllocRMcallAddress(WORD sel,WORD off,NPTRANSLATION call,
  159.                 WORD *rmseg,WORD *rmoff)
  160.         - the real mode call structure is static, causing reentrancy problems
  161.         - the called procedure must modify the real mode CS:IP before returning
  162.         - values are returned to real mode by modifying the
  163.           real mode call struct
  164.  
  165. int FreeRMcallAddress(WORD rmseg,WORD rmoff)
  166.         - frees real mode callback address
  167.  
  168.  
  169. ****** Get Version DPMI 0.9 ******
  170.  
  171. void GetDPMIVersion(DPMIVERSION *)
  172.         DPMIVERSION struct contains:
  173.         - flags:
  174.         bit 0: running under an 80386 (32-bit) implementation
  175.         bit 1: processor returns to real mode for reflected interrupts
  176.            instead of V86 mode
  177.         bit 2: virtual memory supported
  178.         bit 3: reserved (undefined)
  179.         others reserved (zero)
  180.         - cpu : processor type (02h=80286, 03h=80386, 04h=80486)
  181.         - pic
  182.           curr value of virtual master interrupt controller base interrupt
  183.           curr value of virtual slave interrupt controller base interrupt
  184.  
  185.  
  186. ****** Memory management services DPMI 0.9 ******
  187.  
  188. void GetFreeMemInfo(NPFREEMEMINFO freemempointer);
  189.         - get struct contains free mem info
  190.         - struct FREEMEMINFO:
  191.           DWORD   largest available block in bytes
  192.           DWORD   maximum unlocked page allocation
  193.           DWORD   maximum locked page allocation
  194.           DWORD   total linear address space in pages
  195.           DWORD   total unlocked pages
  196.           DWORD   free pages
  197.           DWORD   total physical pages
  198.           DWORD   free linear address space in pages
  199.           DWORD   size of paging file/partition in pages
  200.           DWORD   reserved
  201.           DWORD   reserved
  202.           DWORD   reserved
  203.  
  204. int GlobalAlloc(DWORD bytes,DWORD *handle,DWORD *memaddress);
  205.         - allocate memory block , size = bytes
  206.         - in Windows you get memory page granular. This means that allocation
  207.           of 534 bytes allocate 4096 = 4 KB.
  208.         - handle is used to free memory blocks
  209.  
  210. int GlobalFree(DWORD handle);
  211.         - frees a memory block that was allocate though GlobalAlloc()
  212.  
  213. int GlobalResize(DWORD size,DWORD oldhandle,DWORD *handle,DWORD *newmemaddress);
  214.         - reallocate memory block , size = bytes
  215.     - old handle is unvalid
  216.  
  217.  
  218. ****** Page locking services DPMI 0.9 ******
  219.  
  220. int LockLinRegion(DWORD size,DWORD linaddress);
  221.         - locks linear address range , size = region to lock
  222.  
  223. int UnlockLinRegion(DWORD size,DWORD linaddress);
  224.         - unlock linear address range
  225.  
  226. int MarkRealModePageable(DWORD size,DWORD address);
  227.     - mark real mode region pageable
  228.     - relock region before terminating program
  229.     - use only programs own memory
  230.     - be sure dpmi-host-memory not pageable
  231.  
  232. int RelockRealModeRegion(DWORD size,DWORD address);
  233.     - relocks real mode region
  234.  
  235. int GetPageSize(DWORD *size);
  236.         - get pagesize in bytes
  237.  
  238.  
  239. ****** Damand page performance tuning services DPMI 0.9 ******
  240.  
  241. int MarkPageDemand(DWORD address,DWORD n)
  242.         - mark n pages as demand paging candidate
  243.         - return   0 : successful   -1 : not successful
  244.  
  245. int DiscardPage(DWORD address_of_page,DWORD size)
  246.         - discard contents of page
  247.         - return   0 : successful   -1 : not successful
  248.  
  249.  
  250. ****** Physical Address Mapping DPMI 0.9 ******
  251.  
  252. int PhysicalMap(DWORD address,DWORD size,DWORD *physical)
  253.         - implementations may refuse this call because it can circumvent
  254.           protects
  255.         - the caller must build an appropriate selector for the memory
  256.         - do not use for memory mapped in the first megabyte
  257.  
  258.  
  259. ****** Virtuel interrupt state functions DPMI 0.9 ******
  260.  
  261. BYTE DisableVirtuelInterruptState(void)
  262.         returns  0 if previously disabled
  263.                  1 if previously enabled
  264.         - disable interrupts
  265.         - a CLI instruction may be used if the previous state is unimportant,
  266.       but should be assumed to be very slow due to trapping by the host
  267.  
  268. BYTE EnableVirtuelInterruptState(void)
  269.         returns  0 if previously disabled
  270.                  1 if previously enabled
  271.         - enable interrupts
  272.         - a STI instruction may be used if the previous state is unimportant,
  273.       but should be assumed to be very slow due to trapping by the host
  274.  
  275. BYTE GetVirtuelInterruptState(void)
  276.         returns  0 if previously disabled
  277.                  1 if previously enabled
  278.         - should be used rather than PUSHF
  279.  
  280. ****** Get Vendor Specific Api Entry Point ******
  281.  
  282. int GetVendorEntry(NPBYTE APIname,WORD *selector,WORD *offset)
  283.         - APIname = case-sensitive ASCIZ vendor name or identifier
  284.         - gives entry point for extended function
  285.  
  286.  
  287. ****** Debug Register support DPMI 0.9 ******
  288.  
  289. Constants in dpmi.h for breakpoints
  290.         BREAK_CODE, BREAK_DATA_W1, BREAK_DATA_RW1, BREAK_DATA_W2
  291.         BREAK_DATA_RW2, BREAK_DATA_W4, BREAK_DATA_RW4
  292.  
  293. int SetDebugWatchpoint(DWORD linear_address,WORD break_type,WORD *handle)
  294.         - set breakpoint on linear address
  295.         - types defined in dpmi.h
  296.           data breakpoint : 1/2/4 byte read/write
  297.  
  298. int ClearDebugWatchpoint(WORD handle)
  299.         - clear breakpoint
  300.  
  301. int GetStateDebugWatchpoint(WORD handle, WORD *execute_flag)
  302.         - get state of breakpoint
  303.         - execute_flag=1, if watchpoint has been executed
  304.  
  305. int ResetDebugWatchpoint(WORD handle)
  306.         - reset state of breakpoint
  307.  
  308.  
  309. ****** CPU switching for DPMI 0.9 ******
  310. int hangin_extender(void);
  311.         - installs a DOS-Extender
  312.         - return 0 , if successful
  313.  
  314.  
  315. ****** CPU switching for DPMI 0.9 ******
  316.  
  317. void real_to_protected(WORD type);
  318.         - type=0 16 bit program , type=1 32 bit program
  319.         - call this function switch the cpu in protected mode
  320.         - other funtions are not execute if this function fails
  321.         - cs,ds,es were set by the dpmi host
  322.  
  323. void protected_to_real(WORD errorcode);
  324.         - switch cpu back to real mode
  325.         - terminates the program ( like real mode int21,function 4c)
  326.         - errorcode = errorleved to msdos
  327.  
  328.  
  329. ******* c-functions using DPMI **********
  330.  
  331. int FreeManyLDT(WORD sel,WORD n)
  332.         - this frees n continius selectors
  333.  
  334. void PrintFreeMemInfo(NPFREEMEMINFO freemem);
  335.         - this prints a free memory info
  336.  
  337. void PrintDescriptor(NPDESCRIPTOR descriptor);
  338.         - print the descriptor address,limit,access type etc.
  339.  
  340. void far * IncFP(void far *);
  341.         - increment selector to the next
  342.  
  343. void far * DecFP(void far *);
  344.         - decrement selector to the next
  345.  
  346.  
  347. ****** high level memory functions in the DPMI-Enviroment *******
  348.  
  349. void set_memory_type(WORD type)
  350.     - set memory allocating strategy for extmalloc
  351.     - types 0, XMSLIMIT, LOCKMEM
  352.     - XMSLIMIT allocates only memory <= XMS-POOL
  353.       useful to limit memory for PIF's in Windows 3.0
  354.     - LOCKMEM allocates locked memory only
  355.  
  356. void far *extmalloc(DWORD nbytes);
  357.         - allocates n bytes
  358.         - if n is greater than 64 KB then continues descriptors will be
  359.           allocated. To access the next descriptor add the value return by
  360.           function IncSel() to the base selector
  361.         - return base selector , NULL if insufficient memory available
  362.  
  363. void extfree(void far *filepointer);
  364.         - frees memory that was allocated by extmalloc()
  365.  
  366.  
  367. ******** extended c-functions *********
  368.  
  369. void farcopy(void far *dest,void far *source,DWORD bytes)
  370.         - copy memory block from far pointer to far pointer
  371.         - bytes must min(limit-dest,limit-source) , ( -> GP-fault)
  372.         - useful to copy pointers given by extmalloc(more then 64KB)
  373.  
  374. int extmovedata(void far *source,void far *dest,DWORD bytes)
  375.         - same as movedata for size_t bytes
  376.         - useful to copy pointers given by extmalloc(more then 64KB)
  377.         - offsets should be the same
  378.  
  379.  
  380. ******** others *************
  381.  
  382. int IsWindowsEnhanced(void);
  383.     - return 1 , if Windows Enhanced mode is running
  384.     - else 0
  385.  
  386. int IsPM(void);
  387.         - return 1 if cpu is in protected mode, 0 not
  388.  
  389. void Yield(void);
  390.         - call int 2F function 1680h
  391.         - useful in a program loop in a multitasking environment like Windows
  392.           ( like GetMassage )
  393.  
  394.  
  395. ******* The Protected Mode Interface *******
  396.  
  397. DWORD lsl32(WORD selector);
  398.         - load selector limit
  399.         - uses 32-bit commands , only for >386
  400.         - 286 must use lsl16()
  401.  
  402. WORD lsl16(WORD selector);
  403.         - load selector limit
  404.  
  405. DWORD lar32(WORD selector);
  406.         - load selector access rights and extended access rights
  407.         - uses 32-bit commands , only for >386
  408.  
  409. WORD lar16(WORD selector);
  410.         - load selector access rights
  411.         - 286 must use lar16()
  412.  
  413. WORD verr(WORD selector);
  414.         - verify if read flags is set
  415.         - return 1 : read   0 : not
  416.  
  417. WORD verw(WORD selector);
  418.         - verify if write flag is set
  419.         - return 1 : write  0 : not
  420.  
  421. void sgdt(GDTR *gdtregister);
  422.         - save GDT base address and limit
  423.  
  424. void sidt(GDTR *idtregister);
  425.         - save IDT base address and limit
  426.  
  427. WORD sldt(void);
  428.         - save LDT selector
  429.         - return LDTselector
  430.  
  431. WORD str(void);
  432.         - save task register
  433.         - return TASKselector
  434.  
  435.